/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.exception;

import com.genia.toolbox.basics.exception.BundledException;

/**
 * This interface describe an exception to allow tests to be done.
 * 
 * @param <EXCEPTION>
 *          The exception that is described
 */
public interface ExceptionDescriptor<EXCEPTION extends BundledException>
{

  /**
   * This method returns the class of the exception to be tested.
   * 
   * @return the class of the exception to be tested
   */
  public Class<EXCEPTION> getExceptionClass();



  /**
   * This method returns the default internationnalization key of the exception
   * to be tested.
   * 
   * @return the default internationnalization key of the exception to be tested
   */
  public String getDefaultKey();



  /**
   * This method returns the default message of the exception to be tested.
   * 
   * @return the default message of the exception to be tested
   */
  public String getDefaultMessage();



  /**
   * This method return an <code>EXCEPTION</code> created without parameters.
   * 
   * @return an <code>EXCEPTION</code> created without parameters
   */
  public EXCEPTION getException();



  /**
   * This method return an <code>EXCEPTION</code> created with an
   * internationnalisation key.
   * 
   * @param key
   *          the internationnalisation key of the exception
   * @return an <code>EXCEPTION</code> created with an internationnalisation
   *         key
   */
  public EXCEPTION getException(String key);



  /**
   * This method return an <code>EXCEPTION</code> created from message, the
   * key of the message and the arguments to constructs the message.
   * 
   * @param message
   *          the message of the exception
   * @param key
   *          the internationnalisation key of the exception
   * @param arguments
   *          the arguments of the message
   * @return an <code>EXCEPTION</code> created from message, the key of the
   *         message and the arguments to constructs the message.
   */
  public EXCEPTION getException(String message, String key, Object... arguments);



  /**
   * This method return an <code>EXCEPTION</code> created from an existing
   * <code>Throwable</code>.
   * 
   * @param cause
   *          the underlying throwable cause
   * @return the <code>EXCEPTION</code> created from an existing
   *         <code>Throwable</code>
   */
  public EXCEPTION getException(Throwable cause);



  /**
   * This method return an <code>EXCEPTION</code> created from an existing
   * <code>Throwable</code>, the key of the message and the arguments to
   * constructs the message.
   * 
   * @param cause
   *          the underlying throwable cause
   * @param key
   *          the key used in the internationalization properties file
   * @param arguments
   *          exception arguments to send with the exception object
   * @return the <code>EXCEPTION</code> created from an existing
   *         <code>Throwable</code>, the key of the message and the arguments
   *         to constructs the message
   */
  public EXCEPTION getException(Throwable cause, String key, Object... arguments);



  /**
   * This method return a <code>Throwable</code> to use in the constructors
   * that needs one.
   * 
   * @return a <code>Throwable</code> to use in the constructors that needs
   *         one
   */
  public Throwable getCause();
}
